home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / bbsutil / dlx70bbs.zip / DLX70SRC.ZIP / SOURCE.TXT < prev    next >
Text File  |  1994-03-06  |  8KB  |  184 lines
  1. DLX MULTI-LINE BULLETIN BOARD SYSTEM
  2. Version 7.0
  3.  
  4. *********************
  5. * Source Code Notes *
  6. *********************
  7.  
  8. PUBLIC DOMAIN PROGRAM
  9.  
  10. The DLX programs and files, including the source code, are now public
  11. domain.  This means that you may freely use it, copy it and modify
  12. it, including for commercial purposes.  This is better than shareware
  13. - there is no fee at all for using it.  You may use this code to
  14. develop a modified DLX, or an entirely different BBS, or for whatever
  15. purpose you like.  I have voluntarily surrended my copyright on it
  16. and placed it in the public domain.
  17.  
  18. SOURCE CODE INSTRUCTIONS
  19.  
  20. *** Tools ***
  21.  
  22. I started writing DLX in 1985, using Microsoft Pascal and assembler.
  23. The last version of Microsoft Pascal (Version 4.0) was released in
  24. 1988, so it's getting to be an old compiler now.  In addition, two of
  25. the utility programs are written in C.  In order to build DLX and the
  26. utility programs, you will need the following tools:
  27.  
  28. Microsoft Pascal 4.0
  29.     This is the final version of the Microsoft "high" Pascal compiler.
  30.     MS Pascal 4.0 is no longer made, so you will have to either find
  31.     a used copy, or a dealer with a new copy still in stock.  The
  32.     fact that it is no longer sold doesn't mean it's public domain,
  33.     so please get a legit copy.  You need the 4.0 version; the
  34.     earlier ones won't work.
  35.  
  36.     Now a logical question to ask is: Can I use Borland Turbo Pascal
  37.     instead?  Alas, the dialects of Pascal are different and so it
  38.     won't work.  Likewise, Microsoft Quick Pascal won't work either,
  39.     because    it uses a dialect similar to Turbo Pascal.  Could it be
  40.     translated?  I'm sure it's possible in principle but you'll have
  41.     to do the work (not me!).
  42.  
  43.     When you install Pascal, I suggest that you override the defaults
  44.     and install the binaries in \PASCAL\BIN, the libraries in
  45.     \PASCAL\LIB, the include files in \PASCAL\INCLUDE and so on,
  46.     rather than in root \BIN, \LIB and \INCLUDE.  This will make it
  47.     easier to manage multiple compilers on your hard disk.  Also,
  48.     choose the "altmath" floating point library (libpasa) during setup.
  49.     All MS Pascal 4.0 programs are "medium model" in C terms.
  50.  
  51.     The Microsoft Download Service (1-206-936-6735 modem) has a bug
  52.     fix for MS Pascal 4.0 that fixes incorrect assignment of lstrings.
  53.     The file is called SP0285.EXE.
  54.  
  55. MASM Macro Assembler
  56.     Any recent version should work (5.1 or later), perhaps with a
  57.     little tweaking.  The one I used for this release was MASM 6.11.
  58.     I haven't tried TASM or OPTASM.  I have included the assembled
  59.     .obj files in with the sources, so you don't have to buy a copy
  60.         of MASM if you don't want to fool with the assembler sources.
  61.  
  62. C Compiler (optional)
  63.     The C used for two of the utility programs is pretty generic and
  64.     any C compiler should work.  The one I used for this release was
  65.     Microsoft Visual C++ Version 1.5.  Unless you want to modify
  66.     the two utility programs written in C (RNDB and RNTABS), you
  67.     don't need to go out and buy a C compiler just for DLX work.
  68.  
  69. With two compilers and an assembler installed, it can be a problem
  70. getting the environment variables set up right.  You may have to
  71. experiment a bit for your particular situation.  Here is what I used:
  72.  
  73.     path c:\windows;c:\dos;c:\pascal\bin;c:\msvc\bin;c:\masm611\bin;c:\bin
  74.     set include=c:\pascal\include;c:\msvc\include;c:\masm611\include
  75.     set lib=c:\pascal\lib;c:\msvc\lib;c:\masm611\lib
  76.  
  77.  
  78. *** How to build DLX ***
  79.  
  80. A makefile is included in the sources.  To build from it, just run
  81. Microsoft's NMAKE or an equivalent program.  I used NMAKE version
  82. 1.40 for this release, but the version probably isn't important.
  83. Don't use the MAKE.EXE program included in MS Pascal - that's a
  84. different program altogether and would require a makefile of a
  85. different format.
  86.  
  87. If you prefer to use a batch file instead of a makefile, you can run
  88. BUILD.BAT.
  89.  
  90. Before you start modifying the source code, build the unchanged
  91. sources and make sure that the resulting DLX.EXE that you get has the
  92. same size as the one included in the ZIP file, and compares *exactly*
  93. to it also.  This will ensure that you are starting out from the
  94. right place.
  95.  
  96. The utility programs can be built using the batch file UTILS.BAT.
  97. You will need a C compiler for two of the programs.  Build DLX itself
  98. before you build the utilities, because the utilities use some of the
  99. compiler modules from DLX.
  100.  
  101. *** How DLX Works ***
  102.  
  103. The main program, DLX.PAS, is essentially a round-robin scheduler.
  104. It polls each modem line (and the keyboard) in sequence.  If it finds
  105. any input or output data pending for that line, then the appropriate
  106. routine is called.  Then it goes on to the next line.
  107.  
  108. The modem / serial communications routines in COM_PAX2.ASM include
  109. custom interrupt handlers for conventional serial ports and for
  110. Digiboard cards.  These interrupt handlers are unusual because they
  111. not only capture incoming data, they also echo the incoming
  112. characters back so that the main program does not have to.  They also
  113. handle backspaces and tabs and echo the right things.  Doing this in
  114. the interrupt handler makes every modem line seem "live" and
  115. responsive at all times, even when the main program is busy doing
  116. something else (like a DOS file operation) for another line.
  117.  
  118. The actions that DLX takes in response to input lines is governed by
  119. the script files, SCRIPT0-5.PAS.  These files describe a kind of
  120. state machine.  At all times, every modem line and the console is in
  121. a particular state.  When a new input line of text comes in, the
  122. script files are called with the current state and the new input
  123. line.  The script files do their thing and leave the modem line in a
  124. new state.
  125.  
  126. When adding code the SCRIPT* files, you must be careful how you use
  127. variables.  Local variables will not be around from one state to the
  128. next, so only use them to store values that will not be saved.
  129. Global variables will stick around from call to call, but remember
  130. there's only one copy, so things may appear to work when you test out
  131. the program with just one person (yourself) online and then fail when
  132. two or more people are online.  The proper way to store info in the
  133. SCRIPT* files is to use the q or w arrays of structures.  There is a
  134. q and w record for each telephone line and the console.
  135.  
  136. The other files are essentially collections of utility routines.
  137. Here's a rundown:
  138.  
  139. DATABASE.PAS    Routines to access the members file and pubmail
  140. DATAINIT.PAS    Routines to initialize various data
  141. DLXINIT.PAS    Routines used when starting DLX (initializing modems etc)
  142. DLXUTIL.PAS    Utility routines used by DLX.PAS
  143. EXTNDH.ASM    Utility for more file handles in older MS-DOS versions
  144. FS_PKG.PAS    Routines for reading and writing mail
  145. FUNS.PAS    Ampersand codes
  146. IDENT.PAS    Herald when DLX starts
  147. KBD.ASM     Routines to handle keyboard input
  148. LOAD.PAS    Definitions of prompts
  149. LOADINIT.PAS    Read in prompts, essay, etc.
  150. NEWASM.ASM    Utility routines in assembler (1988 or later)
  151. PASASM.ASM    Utility routines in assembler (old)
  152. SUTILS.PAS    Utility routines for the SCRIPT* files
  153. UTILS.PAS    General utility routines
  154. XMODEM.PAS    XMODEM and XMODEM-1K code
  155.  
  156. Another way to approach DLX is to start with the data formats.  Read
  157. the file TYPES.INT for all the basic types that DLX defines, then
  158. read the file GLOBALS.INT for all the global variables that DLX
  159. defines.
  160.  
  161. *** Compiler Limits
  162.  
  163. Some of the larger source module files are close to the maximum size
  164. that Microsoft Pascal 4.0 can handle.  If you exceed the limit, you
  165. start getting weird, unjustified syntax errors and the like.  The
  166. only solution is to break up the large module into two or more
  167. modules by using the MS Pascal module mechanism.
  168.  
  169. *** Linker Issues
  170.  
  171. DLX uses overlays to keep the amount of memory used by the code to a
  172. minimum.  The code that is used only when starting up (dlxinit,
  173. loadinit and datainit) is overlaid with running code when startup is
  174. complete.  The overlay manager supplied with MS Pascal 4.0 is used.
  175. This overlay manager will not work with all versions of the Microsoft
  176. Link program, and it is safest to link DLX wit